Maîtriser Temporal Duration de JavaScript : Un Guide Complet sur le Calcul d'Intervalles de Temps

L'API Temporal de JavaScript représente une avancée significative dans la gestion des dates et des heures. L'un de ses composants principaux est l'objet Duration, conçu spécifiquement pour représenter des intervalles de temps. Contrairement à l'objet Date traditionnel qui souffre de mutabilité et de complexités liées aux fuseaux horaires, Duration offre une manière plus propre, plus précise et internationalement consciente de travailler avec des durées. Ce guide complet explorera l'objet Duration en détail, couvrant tout, de l'utilisation de base aux scénarios avancés.

Qu'est-ce que Temporal Duration ?

Un Temporal.Duration représente une durée de temps, indépendamment de tout système de calendrier ou fuseau horaire spécifique. Il se concentre uniquement sur la quantité de temps, exprimée en années, mois, jours, heures, minutes, secondes et fractions de seconde. Pensez-y comme "5 ans, 3 mois et 2 jours", plutôt que "du 1er janvier 2023 au 3 mars 2028".

Cette distinction est cruciale car les durées sont intrinsèquement relatives. Ajouter une durée à une date spécifique donnera toujours une nouvelle date, mais le résultat précis dépend du système de calendrier et de la date de départ. Par exemple, ajouter un mois au 31 janvier donne des dates différentes selon que l'année est bissextile ou non.

Créer des objets Duration

Il existe plusieurs façons de créer des objets Temporal.Duration :

1. À partir de composants

La manière la plus directe est d'utiliser la méthode Temporal.Duration.from avec un objet contenant les composants souhaités :

            const duration1 = Temporal.Duration.from({ years: 1, months: 6, days: 15 });
console.log(duration1.toString()); // Sortie : P1Y6M15D

const duration2 = Temporal.Duration.from({ hours: 8, minutes: 30, seconds: 12, milliseconds: 500 });
console.log(duration2.toString()); // Sortie : PT8H30M12.5S

const duration3 = Temporal.Duration.from({ years: 2, days: -5, seconds: 30 });
console.log(duration3.toString()); // Sortie : P2YT-5S30S

            

              
                Copy
              
            
          

Notez que vous pouvez utiliser des valeurs négatives pour représenter des durées qui remontent dans le temps.

2. À partir d'une chaîne ISO 8601

La méthode Temporal.Duration.from accepte également une chaîne de durée ISO 8601 :

            const duration4 = Temporal.Duration.from('P3Y2M10DT5H30M');
console.log(duration4.toString()); // Sortie : P3Y2M10DT5H30M

const duration5 = Temporal.Duration.from('PT1H15M30S');
console.log(duration5.toString()); // Sortie : PT1H15M30S

const duration6 = Temporal.Duration.from('P-1Y');
console.log(duration6.toString()); // Sortie : P-1Y

            

              
                Copy
              
            
          

Le format de durée ISO 8601 est P[années]Y[mois]M[jours]D[T[heures]H[minutes]M[secondes]S]. Le 'P' indique une période (durée), et le 'T' sépare les composants de date et d'heure.

3. Utiliser le constructeur

Vous pouvez également utiliser le constructeur Temporal.Duration directement :

            const duration7 = new Temporal.Duration(1, 2, 3, 4, 5, 6, 7, 8);
console.log(duration7.toString()); // Sortie : P1Y2M3W4DT5H6M7S8ms

            

              
                Copy
              
            
          

Les arguments du constructeur sont dans l'ordre : years, months, weeks, days, hours, minutes, seconds, milliseconds, microseconds, nanoseconds.

Propriétés de Duration

Une fois que vous avez un objet Duration, vous pouvez accéder à ses composants en utilisant ses propriétés :

            const duration = Temporal.Duration.from('P1Y2M3DT4H5M6S');

console.log(duration.years);       // Sortie : 1
console.log(duration.months);      // Sortie : 2
console.log(duration.days);        // Sortie : 3
console.log(duration.hours);       // Sortie : 4
console.log(duration.minutes);     // Sortie : 5
console.log(duration.seconds);     // Sortie : 6
console.log(duration.milliseconds);  // Sortie : 0
console.log(duration.microseconds);  // Sortie : 0
console.log(duration.nanoseconds);   // Sortie : 0

            

              
                Copy
              
            
          

Arithmétique des durées

L'objet Duration fournit des méthodes pour effectuer des opérations arithmétiques :

1. Ajouter des durées

Utilisez la méthode add pour additionner deux durées :

            const duration1 = Temporal.Duration.from('P1Y2M');
const duration2 = Temporal.Duration.from('P3M4D');

const sum = duration1.add(duration2);
console.log(sum.toString()); // Sortie : P1Y5M4D

            

              
                Copy
              
            
          

2. Soustraire des durées

Utilisez la méthode subtract pour soustraire une durée d'une autre :

            const duration1 = Temporal.Duration.from('P1Y2M');
const duration2 = Temporal.Duration.from('P3M4D');

const difference = duration1.subtract(duration2);
console.log(difference.toString()); // Sortie : PPT11M-4D

            

              
                Copy
              
            
          

3. Négation d'une durée

Utilisez la méthode negated pour inverser le signe de tous les composants d'une durée :

            const duration = Temporal.Duration.from('P1Y2M-3D');
const negatedDuration = duration.negated();
console.log(negatedDuration.toString()); // Sortie : P-1YT-2M3D

            

              
                Copy
              
            
          

4. Valeur absolue d'une durée

Utilisez la méthode abs pour obtenir une durée avec tous les composants positifs :

            const duration = Temporal.Duration.from('P-1YT2M-3D');
const absoluteDuration = duration.abs();
console.log(absoluteDuration.toString()); // Sortie : P1YT2M3D

            

              
                Copy
              
            
          

5. Multiplier une durée

Utilisez la méthode multiply pour multiplier une durée par un nombre :

            const duration = Temporal.Duration.from('PT1H30M');
const multipliedDuration = duration.multiply(2.5);
console.log(multipliedDuration.toString()); // Sortie : PT3H45M

            

              
                Copy
              
            
          

6. Arrondir une durée

Utilisez la méthode round pour arrondir une durée à une unité spécifique. Cela nécessite de fournir une option relativeTo, qui peut être un Temporal.PlainDateTime ou Temporal.ZonedDateTime, car certaines unités (comme les mois et les années) ont des longueurs variables.

            const duration = Temporal.Duration.from('P1DT12H30M');
const relativeTo = Temporal.PlainDateTime.from('2024-01-01T00:00:00');

const roundedDuration = duration.round({ smallestUnit: 'days', relativeTo });
console.log(roundedDuration.toString()); // Sortie : P2D

            

              
                Copy
              
            
          

Dans cet exemple, 1 jour et 12 heures sont arrondis à 2 jours.

Comparer des durées

Vous pouvez comparer deux durées en utilisant la méthode compare. Cependant, gardez à l'esprit que les durées avec des unités mixtes (par exemple, des années et des jours) ne peuvent pas être comparées de manière fiable sans un contexte relatif (une date et un calendrier spécifiques). La fonction compare retourne :

• -1 si duration1 est inférieure à duration2
• 0 si duration1 est égale à duration2
• 1 si duration1 est supérieure à duration2

            const duration1 = Temporal.Duration.from('PT1H');
const duration2 = Temporal.Duration.from('PT30M');

console.log(Temporal.Duration.compare(duration1, duration2)); // Sortie : 1
console.log(Temporal.Duration.compare(duration2, duration1)); // Sortie : -1
console.log(Temporal.Duration.compare(duration1, Temporal.Duration.from('PT1H'))); // Sortie : 0

const duration3 = Temporal.Duration.from('P1M');
const duration4 = Temporal.Duration.from('P30D');

// La comparaison directe de duration3 et duration4 lèvera une erreur dans de nombreux moteurs
// à moins que 'relativeTo' ne soit spécifié, car la longueur d'un mois n'est pas constante.

            

              
                Copy
              
            
          

Exemples pratiques et cas d'utilisation

L'objet Temporal.Duration est incroyablement polyvalent et peut être utilisé dans un large éventail d'applications :

1. Calculer la durée d'un projet

Imaginez que vous gérez un projet avec une date de début et une date de fin. Vous pouvez utiliser Temporal.PlainDate et Temporal.Duration pour calculer la durée du projet :

            const startDate = Temporal.PlainDate.from('2024-01-15');
const endDate = Temporal.PlainDate.from('2024-03-20');

const duration = endDate.since(startDate);
console.log(duration.toString()); // Sortie : P1M5D

            

              
                Copy
              
            
          

2. Planifier des événements récurrents

Vous pouvez utiliser Temporal.Duration pour définir la fréquence des événements récurrents, tels que les réunions hebdomadaires ou les rapports mensuels :

            const eventFrequency = Temporal.Duration.from({ weeks: 1 });
let nextEventDate = Temporal.PlainDate.from('2024-01-22');

for (let i = 0; i < 5; i++) {
  console.log(`Événement ${i + 1}: ${nextEventDate.toString()}`);
  nextEventDate = nextEventDate.add(eventFrequency);
}

// Sortie :
// Événement 1: 2024-01-22
// Événement 2: 2024-01-29
// Événement 3: 2024-02-05
// Événement 4: 2024-02-12
// Événement 5: 2024-02-19

            

              
                Copy
              
            
          

3. Calculer l'âge

Bien que le calcul précis de l'âge nécessite de gérer les années bissextiles et les différents systèmes de calendrier, Temporal.Duration peut fournir une bonne approximation :

            const birthDate = Temporal.PlainDate.from('1990-05-10');
const today = Temporal.PlainDate.from('2024-02-15');

const ageDuration = today.since(birthDate);

console.log(`Âge approximatif : ${ageDuration.years} ans, ${ageDuration.months} mois, ${ageDuration.days} jours`);

            

              
                Copy
              
            
          

4. Calculs tenant compte des fuseaux horaires : Durées de vol

Pour les applications mondiales, la gestion des fuseaux horaires est essentielle. Envisagez de calculer la durée des vols entre différents fuseaux horaires :

            const departureZonedDateTime = Temporal.ZonedDateTime.from('2024-03-15T10:00:00[America/Los_Angeles]');
const arrivalZonedDateTime = Temporal.ZonedDateTime.from('2024-03-16T14:30:00[Europe/London]');

const flightDuration = arrivalZonedDateTime.since(departureZonedDateTime);

console.log(`Durée du vol : ${flightDuration.hours} heures, ${flightDuration.minutes} minutes`);
console.log(flightDuration.toString());

            

              
                Copy
              
            
          

Cet exemple montre comment Temporal.ZonedDateTime, combiné avec .since(), s'ajuste automatiquement aux différences de fuseaux horaires, fournissant une durée de vol précise.

5. Suivi des accords de niveau de service (SLA)

De nombreux services en ligne promettent des garanties de disponibilité. Vous pouvez utiliser `Temporal.Duration` pour définir et suivre ces accords.

            const slaGuarantee = Temporal.Duration.from('PT99H59M59S'); // Presque 100 heures
const downtime = Temporal.Duration.from('PT1H');

if (downtime.compare(slaGuarantee) > 0) {
  console.log("SLA non respecté !");
} else {
  console.log("SLA respecté.");
}

            

              
                Copy
              
            
          

Considérations avancées

1. Ambiguïté des mois et des années

Comme mentionné précédemment, la longueur des mois et des années peut varier. Lors de l'exécution de calculs impliquant ces unités, il est souvent nécessaire de fournir un contexte relatif en utilisant Temporal.PlainDateTime ou Temporal.ZonedDateTime. Ceci est particulièrement important lors de l'arrondissement ou de la comparaison des durées.

2. Systèmes de calendrier

L'API Temporal prend en charge différents systèmes de calendrier. Par défaut, elle utilise le calendrier ISO 8601, qui est le plus largement utilisé. Cependant, vous pouvez spécifier d'autres systèmes de calendrier lors de la création d'objets Temporal.PlainDate ou Temporal.ZonedDateTime. Les durées restent indépendantes du calendrier ; elles représentent une quantité de temps.

3. Mises à jour de la base de données des fuseaux horaires

Les règles des fuseaux horaires peuvent changer avec le temps pour des raisons politiques ou géographiques. Il est crucial de maintenir votre base de données de fuseaux horaires à jour pour garantir des calculs précis, en particulier lorsque vous travaillez avec Temporal.ZonedDateTime. Les environnements d'exécution JavaScript modernes gèrent généralement cela automatiquement, mais dans certains environnements, vous devrez peut-être mettre à jour la base de données manuellement.

Meilleures pratiques

• Utilisez les chaînes de durée ISO 8601 pour la sérialisation et l'échange de données. Cela garantit l'interopérabilité et évite l'ambiguïté.
• Préférez Temporal.Duration pour représenter les intervalles de temps, plutôt que de calculer directement la différence entre deux objets Date. Cela conduit à un code plus propre et plus facile à maintenir.
• Soyez conscient de l'ambiguïté des mois et des années, et fournissez toujours un contexte relatif lorsque cela est nécessaire.
• Utilisez Temporal.ZonedDateTime pour les calculs tenant compte des fuseaux horaires.
• Gardez votre base de données de fuseaux horaires à jour.
• Lorsque vous comparez des durées avec des unités mixtes, utilisez toujours round avec un contexte relatif pour garantir une comparaison précise.

Conclusion

L'objet Temporal.Duration offre un moyen puissant et intuitif de travailler avec des intervalles de temps en JavaScript. En comprenant ses propriétés, ses méthodes et les meilleures pratiques, vous pouvez écrire un code plus robuste, plus précis et internationalement conscient. L'API Temporal, et l'objet Duration en particulier, représentent une avancée significative dans la gestion des dates et des heures en JavaScript, facilitant la création d'applications à la fois précises et pertinentes à l'échelle mondiale. Adoptez l'API Temporal et libérez son potentiel pour simplifier vos calculs liés au temps.

À mesure que l'API Temporal continue d'évoluer, restez informé des nouvelles fonctionnalités et des mises à jour. La proposition officielle ECMAScript et la documentation associée sont d'excellentes ressources pour rester à jour.